home *** CD-ROM | disk | FTP | other *** search
/ Libris Britannia 4 / science library(b).zip / science library(b) / PROGRAMM / ASSEMBLE / H055.ZIP / DOC / MACRO.DOC < prev    next >
Text File  |  1988-01-07  |  19KB  |  483 lines
  1.  
  2. MACRO.DOC PC/370 macro pre-processor documentation
  3.  
  4. Resolution of macros in a PC370 Assembler source program is achieved
  5. by means of a preprocessor.  To invoke the preprocessor, just type the
  6. following:
  7.  
  8. M370 filespec
  9.  
  10. "filespec" is in the standard DOS format for file specification.  The
  11. file extension is optional: if one is specified, it can be just
  12. anything; if none is specified, MLC is the default. To indicate a file
  13. with no extension, you must terminate the name by a period with
  14. nothing behind.
  15.  
  16. The source program will be examined, with all references to macro
  17. instructions causing the appropriate expansion to be performed.  A new
  18. file with the same file name and ALC as the extension will be created
  19. on the same drive as the input, ready to be passed to A370.  For
  20. instance, typing M370 MYPROG will cause MYPROG.MLC to be read from the
  21. default drive and MYPROG.ALC to be written on the same drive.
  22.  
  23. Macros themselves must each constitute one separate file with the
  24. filename equal to the macro name and the extension equal to MAC, for
  25. instance OPEN.MAC.  Macros will always be read from the default drive
  26. (if this drive is a RAM disk, access is extremely fast).
  27.  
  28. Macros can have both positional and keyword parameters.  In a macro,
  29. references to parameters is via the & character:
  30.  
  31.    - &n ("n" being replaced by one digit from 1 to 9) refers to the
  32.      nth positional parameter;
  33.  
  34.    - &xxxxxxxx ("xxxxxxxx" being replaced by a name from one to eight
  35.      letters and/or digits) refers to keyword parameter xxxxxxxx.
  36.  
  37. There are two predefined and system-maintained keyword parameters:
  38.  
  39.    - &LABEL$$ refers to the label; it always returns an eight-
  40.      character label padded with blanks if necessary;
  41.  
  42.    - &N$ references an internal three-digit counter incremented by one
  43.      at every occurrence of a macro instruction in the source program:
  44.      it can be appended to labels generated in the macro expansion to
  45.      make them unique.
  46.  
  47. References to parameters may be inserted anywhere:  between commas,
  48. parentheses or quotes, and even in comments.  If a parameter is to be
  49. immediately followed by letters or digits, a separating period must be
  50. used, for instance &PARM.DATA (the period will be dropped at expansion
  51. time).  In other cases, the period is optional:  for instance, one may
  52. code &PARM(R1) or &PARM.(R1) indifferently.  If a parameter is to be
  53. followed by a period, two consecutive periods must be coded, for
  54. instance &NAME..COM.
  55.  
  56. The length of a parameter can be tested in a AIF instruction by coding
  57. K'&xxxxxxxx as the subject; the complement must then be a numeric
  58. value.
  59.  
  60. Macros may contain five special opcodes:
  61.  
  62.   MACRO  which, if present, must be in the very first line of the
  63.   macro.  It is used to supply the default values of the parameters.
  64.   The MACRO statement may extend on multiple lines.
  65.  
  66.   SETC  which is used to set a new value in an existing parameter or
  67.   in a macro work-parameter. The first execution of a SETC instruction
  68.   for a new parameter name creates that parameter: no prior definition
  69.   is needed.  The format of the SETC instruction is as follows:
  70.  
  71.          xxxxxxxx SETC  value
  72.  
  73.   "xxxxxxxx" is the name of the parameter, without the leading &
  74.   character.  "value" is any value; if it is enclosed in quotes, these
  75.   quotes will not be returned when the parameter is referenced.
  76.  
  77.   AIF  in which only one condition can be tested.  The relation signs
  78.   supported are = # > <.  If, after resolution of all ¶meters, the
  79.   two sides of the equation are composed of digits only, regardless of
  80.   the respective numbers of digits, the comparison is numeric
  81.   (negative values are not supported).  If K'¶meter is coded as
  82.   the first member and the second member is composed of digits only,
  83.   the comparison is also numeric.  Otherwise, the comparison is
  84.   alphanumeric and the length of the complement determines the number
  85.   of characters compared from the subject.  Both the subject and the
  86.   complement may be coded as is, quotes being optional.  The
  87.   complement may contain any character except the period because the
  88.   period indicates the end of the complement.  At the same time, the
  89.   period is the first character of the label where to go if the
  90.   condition is true.
  91.  
  92.   AGO  in which you code a label where to proceed unconditionally.
  93.   This label should begin with a period.
  94.  
  95.   ANOP  which is a no-op.
  96.  
  97. Labels start with a period and can be 2 to 8 characters long.  They
  98. can be attached to a AIF, AGO or ANOP instruction or to any regular
  99. Assembler statement in which case the label is erased during the
  100. expansion process.  All AIF and AGO statements referencing a label
  101. must come before this label; in other words, branching backward is not
  102. permitted.
  103.  
  104. Lines of comments may be inserted in a macro simply by coding .* in
  105. the first two positions. These lines will be ignored during the
  106. expansion of the macro.
  107.  
  108.          *****************************
  109.  
  110. In the input source program, references to macros can freely be coded.
  111. Parameters may extend on multiple lines.  Each of these input lines is
  112. changed into a comment line on the output.
  113.  
  114. If continuation lines are used, the continued line must stop on a
  115. comma as the last character or followed by at least one blank and
  116. optional comments; the continuation line may restart in any position.
  117. No continuation indicator in column 72 is needed.
  118.  
  119. Positional and keyword parameters may be intermixed.  If the value of
  120. a parameter is a literal in quotes, these quotes are passed as an
  121. integral part of the value: if necessary, you can get rid of them by
  122. issuing a SETC statement moving the parameter into itself.
  123. Consecutive commas can be coded to skip a positional parameter and
  124. keep its default value.
  125.  
  126.          *****************************
  127.  
  128. Here are two examples of macros:
  129.  
  130. DCB  MACRO DSORG=S,RECFM=F,MACRF=G,LRECL=80,BLKSIZE=0,
  131.         EODAD=0,SYNAD=&EODAD,RECORD=0
  132. &LABEL$$ DS    0F,0CL86
  133.   DC    C'ADCB'
  134.   AIF   &DDNAME=(.DDX  format DDNAME=(FIELD) ?
  135.   DC    A(DCBDD&N$)    no, use generated ddname field
  136.   AGO   .DDZ
  137. .DDX  DC    A(&DDNAME)
  138. .DDZ  AIF   &MACRF>P.BDAM  is MACRF equal to R or W ?
  139.   DC    X'FFFF',X'00'
  140.   DC    CL1'&DSORG',CL1'&MACRF',CL1'&RECFM'
  141.   DC    X'0A1A'
  142.   DC    H'&LRECL',H'&BLKSIZE'
  143.   DC    A(&EODAD,&SYNAD,&RECORD)
  144.   DC    54X'00'
  145.   AGO   .DDN
  146. .BDAM  AIF   '&RECORD'='0'.NOREC  has RECORD parameter been omitted ?
  147.   DC    X'FFFF',X'40'
  148.   AGO   .DSORG
  149. .NOREC  DC    X'FFFF',X'00'
  150. .DSORG  DC    CL1'&DSORG',CL1'&MACRF',CL1'&RECFM'
  151.   DC    X'0A1A'
  152.   AIF   '&BLKSIZE'='0'.NOBLK   has BLKSIZE been omitted ?
  153.   DC    H'&BLKSIZE',H'&BLKSIZE'
  154.   AGO   .ADRS
  155. .NOBLK  DC    H'&LRECL',H'&LRECL'
  156. .ADRS  DC    A(&EODAD,&SYNAD,0,&RECORD)
  157.   DC    50X'00'
  158. .DDN  AIF   &DDNAME=(.END  is DDNAME a field name ?
  159. DDNAME  SETC  &DDNAME  to remove quotes if any
  160. DCBDD&N$ DC    C'&DDNAME',X'00'
  161. .END  ANOP
  162.  
  163. Note in the above example that the default value for SYNAD is that
  164. specified or assumed for EODAD.
  165.  
  166.  
  167.  
  168. OPEN  MACRO
  169.   AIF   '&LABEL$$'='        '.GO  is label field blank?
  170. &LABEL$$ EQU   *
  171. .GO  AIF   &1=(.REG  is it OPEN  (register) ?
  172.   LA    2,&1
  173.   AGO   .SVC
  174. .REG  AIF   &1=(2).SVC  is it OPEN (2) ?
  175.   LR    2,&1
  176. .SVC  SVC   1
  177.  
  178.  
  179.  
  180. Here is an example of a program using the BEGIN, WTO, OPEN, GET, PUT,
  181. CLOSE, RETURN and DCB macros:
  182.  
  183.  
  184. TEST  BEGIN
  185.   WTO   'DEMONSTRATING THE USE OF MACROS'
  186.   OPEN  FILE1
  187.   OPEN  FILE2
  188. LOOP  GET   FILE1,RECORD
  189.   PUT   FILE2,RECORD
  190.   B     LOOP
  191. EOJ  CLOSE FILE1
  192.   CLOSE FILE2
  193.   RETURN
  194. FILE1  DCB   LRECL=256,RECFM=T,MACRF=G,EODAD=EOJ,
  195.         DDNAME='MYFILE.IN'
  196. FILE2  DCB   LRECL=256,RECFM=T,MACRF=P,
  197.         DDNAME='MYFILE.OUT'
  198. RECORD  DS    CL256
  199.   END
  200.  
  201. Run BAT\RUNMAC.BAT for macro demo programs.
  202.  
  203. ********************************************************************
  204.  
  205.       If you find the macro preprocessor useful and want to support
  206.       future enhancements, please send $20.00 to:
  207.  
  208.       Jacques Roy
  209.       XL SOFTWARE INC.
  210.       1000 St-Jean-Baptiste #120
  211.       Quebec City CANADA G2E 5G5
  212.  
  213. ********************************************************************
  214.  
  215. The following macros are included in the MAC directory for use with
  216. the M370.COM preprocessor.  For more information on M370, see
  217. DOC\USER.DOC and BAT\RUNMAC.BAT.
  218.  
  219. BEGIN  SAVE={YES|NO},BASES={1|2}
  220.  
  221.   Generate CSECT and standard program beginning.
  222.   Parameters are optional. Defaults are SAVE=YES,BASES=1.
  223.   Unless SAVE=NO is specified, a save area is defined and register 13
  224.   is established as the first base register. Register 12 will be
  225.   established as the second base register if BASES=2 is specified.
  226.   If SAVE=NO is specified, register 12 is established as the only base
  227.   register: in this case, the program should not modify the contents
  228.   of register 13.
  229.  
  230. CALL   pgm
  231.  
  232.   Load address of external subroutine pgm into register 15 and
  233.   branch and link via register 14 to address in register 15.
  234.  
  235. CLOSE  dcb
  236.  
  237.   Close a file.  The parameter is mandatory and must be either the
  238.   name of a DCB, or a register in brackets pointing to a DCB.
  239.  
  240.  
  241. DCB  DDNAME=ddname
  242.   DSORG=org
  243.   RECFM=format
  244.   MACRF=macro
  245.   LRECL=reclength
  246.   BLKSIZE=blklength
  247.   EODAD=eof
  248.   SYNAD=err
  249.   RECORD=fieldname
  250.  
  251.   Generate a DCB for PC/370 file access.  See DOC\SYSTEM.DOC for more
  252.   information.  Only DDNAME is required; all other parameters have
  253.   default values.  Parameters can be specified in any order.
  254.  
  255.   "ddname" can be: - a filename of one to eight characters only (no
  256.        device specification, no extension);
  257.      - a literal in quotes of 1 to 64 characters that represents a
  258.        valid DOS file specification;
  259.      - the name in brackets of a 1 to 64-character field
  260.        containing a valid DOS file specification, in EBCDIC.
  261.   "org"       can be S or R; the default is S.
  262.   "format"    can be F, V or T; the default is F.
  263.   "macro"     can be G, P, R or W; the default is G.
  264.   "reclength" is a number representing the record length; the default
  265.        is 80.
  266.   "blklength" is a number representing the block size; the default is
  267.        0.
  268.   "eof"       is the address where to go at end of file; default is 0;
  269.        must be
  270.        supplied for an input file.
  271.   "eof"       is the address where to go in case of an error while
  272.        attempting to handle the file; default is the same as for
  273.        EODAD.
  274.   "record"    is the address of a field where data will be read into
  275.        or written from; default is no such field: record area will be
  276.        specified in GET, PUT, READ or WRITE macros.
  277.  
  278. DISPLAY  fieldname
  279.  
  280.   Display text contained in fieldname on console.  Text must be in
  281.   ASCII with ending line feed X'0A'.
  282.  
  283.  
  284. FREEMAIN R,LV=length,A=address
  285.   E,LV=length,A=address
  286.   V,A=values
  287.  
  288.   Release dynamically allocated memory.
  289.   Use only one of the three possible formats.
  290.  
  291.   If R or E (register or elementary format) is coded as the first
  292.   parameter, both LV and A are mandatory. "length" is either the
  293.   number of bytes to be released or a register in brackets containing
  294.   the number of bytes to be released.  "address" is either the name of
  295.   a full word or a register in brackets containing the address of the
  296.   memory area to be released.
  297.  
  298.   If V (variable format) is coded as the first parameter, only A is
  299.   mandatory. "values" must be the name of two consecutive full words
  300.   that must respectively contain the address and the size of the
  301.   memory area to be released.
  302.  
  303.  
  304. GET  dcb,record
  305.  
  306.   Read next sequential fixed, variable, or text record from buffered
  307.   file.  The first parameter is mandatory and must be either the name
  308.   of a DCB, or a register in brackets pointing to a DCB.
  309.   The second parameter is optional and may be either the name of a
  310.   field or a register in brackets pointing to a field into which the
  311.   record will be read.  If the second parameter is omitted, the area
  312.   pointed to by the RECORD parameter in the DCB will be used and its
  313.   address will be passed in register 1.
  314.  
  315.  
  316. GETMAIN  RU,LV=length
  317.   EU,LV=length,A=fieldname
  318.   VU,LA=sizes,A=values
  319.  
  320.   Dynamically allocate memory.
  321.   Use only one of the three possible formats.
  322.  
  323.   If RU (unconditional register request) is coded as the first
  324.   parameter, LV is mandatory and "length" is either the number of
  325.   bytes requested or a register in brackets containing the number of
  326.   bytes requested.  The address of the allocated memory will be
  327.   returned in register 1.
  328.  
  329.   If EU (unconditional elementary request) is coded as the first
  330.   parameter, both LV and A are mandatory. "length" is either the
  331.   number of bytes requested or a register in brackets containing the
  332.   number of bytes requested.   "fieldname" must be the name of a full
  333.   word into which the address of the allocated memory will be
  334.   returned.
  335.  
  336.   If VU (unconditional variable request) is coded as the first
  337.   parameter, both LA and A are mandatory. "sizes" must be the name of
  338.   two consecutive full words that must respectively contain the
  339.   minimum and the maximum number of bytes requested.   "values" must
  340.   be the name of two consecutive full words that will respectively be
  341.   used to receive the address and the size of the allocated memory.
  342.  
  343.  
  344. LINK  EP=filename
  345.   EP='literal'
  346.   EPLOC=fieldname
  347.   EPLOC=(register)
  348.  
  349.   Dynamically load a module, branch and link to it, and then release
  350.   memory.  Module's entry point is assumed to be at X'210'.
  351.   Use only one of the four forms for parameters.  "filename" is one to
  352.   eight characters only: the default drive and the extension of COM
  353.   are assumed.  "literal', or "fieldname", or field pointed to by
  354.   "register", must contain an EBCDIC character string representing a
  355.   valid DOS file specification.
  356.  
  357.  
  358. LOAD  EP=filename
  359.   EP='literal'
  360.   EPLOC=fieldname
  361.   EPLOC=(register)
  362.  
  363.   Dynamically load a module (can be any file type). Register 15 will
  364.   contain the address where the module was loaded and register 1 will
  365.   contain the module's length.  Register 0 will contain the module's
  366.   entry point assumed to be at X'210' from the beginning (only
  367.   applicable if loading a COM module generated by PC370).
  368.   Use only one of the four forms for parameters.  "filename" is one to
  369.   eight characters only: the default drive and the extension of COM
  370.   are assumed.  "literal', or "fieldname", or field pointed to by
  371.   "register", must contain an EBCDIC character string representing a
  372.   valid DOS file specification.
  373.  
  374.  
  375. OPEN  dcb
  376.  
  377.   Open a file.  The parameter is mandatory and must be either the name
  378.   of a DCB, or a register in brackets pointing to a DCB.
  379.  
  380.  
  381. PUT  dcb,record
  382.  
  383.   Write next sequential fixed, variable, or text record to buffered
  384.   file.  The first parameter is mandatory and must be either the name
  385.   of a DCB, or a register in brackets pointing to a DCB.
  386.   The second parameter is optional and may be either the name of a
  387.   field or a register in brackets pointing to a field from which the
  388.   record will be written.  If the second parameter is omitted, the
  389.   area pointed to by the RECORD parameter in the DCB will be used.
  390.  
  391.  
  392. READ  dcb,record,{rbn | RBN=rbn | RBA=rba}
  393.  
  394.   Read a block from a file.  The first parameter is mandatory and must
  395.   be either the name of a DCB, or a register in brackets pointing to a
  396.   DCB.  The second parameter is optional and may be either the name of
  397.   a field or a register in brackets pointing to a field into which the
  398.   record will be read.  If the second parameter is skipped (by coding
  399.   two consecutive commas), the area pointed to by the RECORD parameter
  400.   in the DCB will be used and its address will be passed in register
  401.   1.  The third parameter is mandatory and may be either positional or
  402.   the keyword RBN or RBA.  The value may be either a number, or the
  403.   name of a full-word containing the number, or a register in brackets
  404.   containing the number.  "rbn" is the relative block number of the
  405.   record (first block is 0).  "rba" is the relative byte address of
  406.   the record (first byte is 0).
  407.  
  408.  
  409. REGS
  410.  
  411.   Generate R0 through R15 register equates.
  412.  
  413. RETURN  RC=nnnn,SAVE={YES|NO}
  414.  
  415.   Exit using standard linkage conventions. Parameters are optional;
  416.   default is SAVE=YES.  If RC is specified, return code nnnn is placed
  417.   in register 15; otherwise, register 15 is restored like all other
  418.   registers.  Specify SAVE=NO if SAVE=NO was specified in the BEGIN
  419.   macro.
  420.  
  421.  
  422. WRITE  dcb,record,{rbn | RBN=rbn | RBA=rba}
  423.  
  424.   Write a block to a file.  The first parameter is mandatory and must
  425.   be either the name of a DCB, or a register in brackets pointing to a
  426.   DCB.  The second parameter is optional and may be either the name of
  427.   a field or a register in brackets pointing to a field from which the
  428.   record will be written.  If the second parameter is skipped (by
  429.   coding two consecutive commas), the area pointed to by the RECORD
  430.   parameter in the DCB will be used.  The third parameter is mandatory
  431.   and may be either positional or the keyword RBN or RBA.  The value
  432.   may be either a number, or the name of a full-word containing the
  433.   number, or a register in brackets containing the number.  "rbn" is
  434.   the relative block number of the record (first block is 0).  "rba"
  435.   is the relative byte address of the record (first byte is 0).
  436.  
  437.  
  438. WTO  message,length
  439.  
  440.   Display a message to the console.  The first parameter is mandatory
  441.   and must be either a literal in quotes or   the name of a field
  442.   containing the message to be displayed, in EBCDIC.  The second
  443.   parameter is optional and applies only if the first parameter is a
  444.   field name. It is used to indicate the number of characters to be
  445.   displayed if this number is other than the field's length.
  446.  
  447.  
  448. WTOR  message,reply
  449.  
  450.   Display a message to the console and wait for reply.  The first
  451.   parameter is optional and may be either a literal in quotes or
  452.   the name of a field containing the message to be displayed, in
  453.   EBCDIC.  The first parameter may be skipped (by coding WTOR  ,reply)
  454.   if no message need be displayed and only a reply is to be
  455.   solicited.  The second parameter is mandatory and must be the name
  456.   of a field into which the reply will be placed, in EBCDIC and padded
  457.   with blanks if necessary.  Operator needs not issue a carriage
  458.   return when reply field is full.
  459.  
  460.  
  461. WTORPC  message,reply
  462.  
  463.   Display a message to the console and wait for reply.  Exactly the
  464.   same coding as for WTOR above, except that it is achieved using
  465.   typical PC features and that the reply's maximum length is 16
  466.   characters.  When entering the reply, the backspace and left-arrow
  467.   can be used to correct typing errors.  Moreover, if the same WTORPC
  468.   is executed again, the right-arrow as well as the F1-F3 keys can be
  469.   used to repeat characters from the previous reply.  The carriage
  470.   return must always be issued to transmit the reply.
  471.  
  472.  
  473.       ***********************************
  474.  
  475. Feel free to develop your own macros in addition to those supplied
  476. with the system.  If you would like to make other users benefit from
  477. general-purpose macros you have written, please send your macro
  478. definitions, documentation and example of use to:
  479.  
  480.    Jacques Roy
  481.    XL SOFTWARE INC.
  482.    1000 St-Jean-Baptiste #120
  483.    Quebec City  CANADA  G2E 5G5